home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / stringref.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  5KB  |  147 lines
  1. /**
  2.  * @file stringref.h Reference-counted immutable strings
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  *
  25.  */
  26. #ifndef _GAIM_STRINGREF_H_
  27. #define _GAIM_STRINGREF_H_
  28.  
  29. /**
  30.  * The internal representation of a stringref.
  31.  *
  32.  * @note For this structure to be useful, the string contained within
  33.  * it must be immutable -- for this reason, do _not_ access it
  34.  * directly!
  35.  */
  36. typedef struct _GaimStringref {
  37.     guint32 ref;    /**< The reference count of this string.
  38.                      *   Note that reference counts are only
  39.                      *   31 bits, and the high-order bit
  40.                      *   indicates whether this string is up
  41.                      *   for GC at the next idle handler...
  42.                      *   But you aren't going to touch this
  43.                      *   anyway, right? */
  44.     char value[1];    /**< The string contained in this ref.
  45.                      *   Notice that it is simply "hanging
  46.                      *   off the end" of the ref ... this
  47.                      *   is to save an allocation. */
  48. } GaimStringref;
  49.  
  50. /**
  51.  * Creates an immutable reference-counted string object.  The newly
  52.  * created object will have a reference count of 1.
  53.  *
  54.  * @param value This will be the value of the string; it will be
  55.  *              duplicated.
  56.  *
  57.  * @return A newly allocated string reference object with a refcount
  58.  *         of 1.
  59.  */
  60. GaimStringref *gaim_stringref_new(const char *value);
  61.  
  62. /**
  63.  * Creates an immutable reference-counted string object.  The newly
  64.  * created object will have a reference count of zero, and if it is
  65.  * not referenced before the next iteration of the mainloop it will
  66.  * be freed at that time.
  67.  *
  68.  * @param value This will be the value of the string; it will be
  69.  *              duplicated.
  70.  *
  71.  * @return A newly allocated string reference object with a refcount
  72.  *         of zero.
  73.  */
  74. GaimStringref *gaim_stringref_new_noref(const char *value);
  75.  
  76. /**
  77.  * Creates an immutable reference-counted string object from a printf
  78.  * format specification and arguments.  The created object will have a
  79.  * reference count of 1.
  80.  *
  81.  * @param format A printf-style format specification.
  82.  *
  83.  * @return A newly allocated string reference object with a refcount
  84.  *         of 1.
  85.  */
  86. GaimStringref *gaim_stringref_printf(const char *format, ...);
  87.  
  88. /**
  89.  * Increase the reference count of the given stringref.
  90.  *
  91.  * @param stringref String to be referenced.
  92.  *
  93.  * @return A pointer to the referenced string.
  94.  */
  95. GaimStringref *gaim_stringref_ref(GaimStringref *stringref);
  96.  
  97. /**
  98.  * Decrease the reference count of the given stringref.  If this
  99.  * reference count reaches zero, the stringref will be freed; thus
  100.  * you MUST NOT use this string after dereferencing it.
  101.  *
  102.  * @param stringref String to be dereferenced.
  103.  */
  104. void gaim_stringref_unref(GaimStringref *stringref);
  105.  
  106. /**
  107.  * Retrieve the value of a stringref.
  108.  *
  109.  * @note This value should not be cached or stored in a local variable.
  110.  *       While there is nothing inherently incorrect about doing so, it
  111.  *       is easy to forget that the cached value is in fact a
  112.  *       reference-counted object and accidentally use it after
  113.  *       dereferencing.  This is more problematic for a reference-
  114.  *       counted object than a heap-allocated object, as it may seem to
  115.  *       be valid or invalid nondeterministically based on how many
  116.  *       other references to it exist.
  117.  *
  118.  * @param stringref String reference from which to retrieve the value.
  119.  *
  120.  * @return The contents of the string reference.
  121.  */
  122. const char *gaim_stringref_value(const GaimStringref *stringref);
  123.  
  124. /**
  125.  * Compare two stringrefs for string equality.  This returns the same
  126.  * value as strcmp would, where <0 indicates that s1 is "less than" s2
  127.  * in the ASCII lexicography, 0 indicates equality, etc.
  128.  *
  129.  * @param s1 The reference string.
  130.  *
  131.  * @param s2 The string to compare against the reference.
  132.  *
  133.  * @return An ordering indication on s1 and s2.
  134.  */
  135. int gaim_stringref_cmp(const GaimStringref *s1, const GaimStringref *s2);
  136.  
  137. /**
  138.  * Find the length of the string inside a stringref.
  139.  *
  140.  * @param stringref The string in whose length we are interested.
  141.  *
  142.  * @return The length of the string in stringref
  143.  */
  144. size_t gaim_stringref_len(const GaimStringref *stringref);
  145.  
  146. #endif /* _GAIM_STRINGREF_H_ */
  147.